[26.1] User based throughput quotas by kbatuigas · Pull Request #1596 · redpanda-data/docs

kbatuigas · 2026-03-03T03:56:20Z

Description

This pull request introduces significant improvements to the documentation for configuring and understanding throughput quotas in Redpanda, with a focus on clarifying the distinction between user-based and client-based quotas, explaining quota precedence and tracking, and providing detailed, actionable configuration instructions.

A new conceptual guide has been added, and the practical guide has been expanded and reorganized for clarity and completeness.

Key documentation improvements:

Conceptual clarity and new guide

Added a new conceptual page about-throughput-quotas.adoc that explains the differences between user-based and client-based quotas, entity hierarchy, precedence rules, and quota tracking behavior. This guide helps users choose the right quota type for their use case and understand how Redpanda enforces quotas.
Updated the navigation (nav.adoc) to include the new conceptual guide for easy discovery.

Enhanced practical configuration instructions

Expanded manage-throughput.adoc with clear learning objectives, detailed descriptions of both user-based and client-based quotas, and step-by-step instructions for configuring, viewing, and deleting quotas using rpk. The guide now covers combined (user, client) quotas, default quotas, and best practices for multi-tenant environments. [1] [2]
Provided explicit instructions and examples for setting, viewing, and removing quotas for users, clients, and combinations thereof, including command-line examples for each scenario.

Improved quota monitoring and enforcement explanation

Clarified how quota enforcement and tracking works, including how unauthenticated connections are treated (user="" vs. user=<default>), and how throughput is tracked independently for each (user, client_id) pair. [1] [2]
Added details on how to monitor connections and quota usage, including new examples for listing connections by user and interpreting the output. [1] [2]

User experience and structure

Reorganized the documentation to separate conceptual understanding from configuration steps, improving readability and helping users find the information they need more quickly. [1] [2]
Updated section headings and added learning objectives for better guidance and discoverability.

References: [1] [2] [3] [4] [5] [6] [7]

Resolves https://redpandadata.atlassian.net/browse/
Review deadline: 9 Mar

Page previews

Manage Throughput
NEW: About Throughput Quotas

Checks

New feature
Content gap
Support Follow-up
Small fix (typos, links, copyedits, etc)

netlify · 2026-03-03T03:56:25Z

✅ Deploy Preview for redpanda-docs-preview ready!

Name	Link
🔨 Latest commit	`5113b70`
🔍 Latest deploy log	https://app.netlify.com/projects/redpanda-docs-preview/deploys/69b203a7b829cb00087272d3
😎 Deploy Preview	https://deploy-preview-1596--redpanda-docs-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

coderabbitai · 2026-03-03T03:56:31Z

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: c88a48ef-359a-4f9c-aaf8-3944cb131706

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch DOC-1792-document-feature-user-based-throughput-quotas

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

modules/manage/pages/cluster-maintenance/about-throughput-quotas.adoc

modules/manage/pages/cluster-maintenance/manage-throughput.adoc

modules/manage/pages/cluster-maintenance/about-throughput-quotas.adoc

modules/manage/pages/cluster-maintenance/manage-throughput.adoc

Co-authored-by: Gellért Peresztegi-Nagy <gellert.nagy@redpanda.com>

kbatuigas · 2026-03-05T23:37:01Z

modules/manage/pages/cluster-maintenance/manage-throughput.adoc

+
+To identify which clients are actively connected and generating traffic, see <<view-connected-client-details>>.
+
+// TODO: Verify the exact quota_rule label values for user-based quotas in v26.1.


@pgellert Would you mind confirming that the label values are as described here?

Yeah, good point, they do change. These are the set of values that are possible (a bunch of new rule values added, and the old cluster_ ones don't exist anymore): https://github.com/redpanda-data/redpanda/blob/a8aa17c80aaa60d6c4ac55e43c50eaf7da43372c/src/v/kafka/server/client_quota_translator.cc#L111-L133

@pgellert according to our metrics docs generation tool + Claude Code, the label name also changed (redpanda_quota_rule, alongside redpanda_quota_type), I went ahead and added that in this doc but if you could please also double check, that would be helpful.

Thanks, the label names are indeed redpanda_quota_type and redpanda_quota_type. They have always been that, though, so that was a typo from earlier, rather than a change in 26.1.

modules/manage/pages/cluster-maintenance/about-throughput-quotas.adoc

mattschumpert · 2026-03-06T04:57:09Z

modules/manage/pages/cluster-maintenance/about-throughput-quotas.adoc

+Use user-based quotas when:
+
+* You operate a multi-tenant environment, such as SaaS platforms or enterprises with departments.
+* You require isolation between users or tenants, including for compliance requirements.


"* You require isolation between users or tenants, to avoid noisy neighbor issues."

@mattschumpert Updated this line, and also updated the intro to this doc: https://deploy-preview-1596--redpanda-docs-preview.netlify.app/current/manage/cluster-maintenance/about-throughput-quotas/

Redpanda uses throughput quotas to limit the rate of produce and consume requests from clients. Understanding how quotas work helps you prevent individual clients from disproportionately consuming resources and causing performance degradation for other clients (also known as the "noisy-neighbor" problem), and ensure fair resource sharing across users and applications.

How does this sound?

modules/manage/pages/cluster-maintenance/manage-throughput.adoc

pgellert

lgtm, thank you!

modules/manage/pages/cluster-maintenance/about-throughput-quotas.adoc

Feediver1 · 2026-03-10T00:58:01Z

modules/manage/pages/cluster-maintenance/about-throughput-quotas.adoc

+
+Redpanda provides two types of throughput limits: broker-wide limits configured using cluster properties and client quotas configured using Kafka API. 
+
+This page covers client quotas, which enable per-user and per-client rate limiting with fine-grained control through entity hierarchy and precedence rules. For information about broker-wide limits, see xref:manage:cluster-maintenance/manage-throughput.adoc#broker-wide-throughput-limits[Broker-wide throughput limits].


This confused me: "This page"...we don't typically use that to describe the content, do we? I see that client quotas is a sub-topic within Quota entities, but there are also other topics covered here too, like user-based quotas.

Is there an issue here with heading hierarchy?

We have used "This page" in other docs. Updated to use "Client ID-based" when referring specifically to quota rules that use the client ID (or ID prefix) for matching

modules/manage/pages/cluster-maintenance/about-throughput-quotas.adoc

Feediver1 · 2026-03-10T01:14:22Z

modules/manage/pages/cluster-maintenance/about-throughput-quotas.adoc

+* User-only quotas share across client_ids: When you configure a quota at the user level (for example, `/config/users/alice`) without specifying a `client_id` dimension, all connections from that user share a single quota bucket regardless of their `client_id`.
+* Client-id-only quotas share across users: When you configure a quota at the `client_id` level (for example, `/config/clients/app-1`) without specifying a user dimension, all users connecting with that `client_id` share a single quota bucket.
+* Combined quotas for per-(user, client_id) tracking: To get independent quota tracking per (user, client_id) combination, configure quotas that include both dimensions, such as `/config/users/<user>/clients/<client-id>` or `/config/users/<default>/clients/<default>`.
+* Prefix-based quotas group clients: Client ID prefix quotas (for example, `/config/client-id-prefix/app-`) cause all clients whose `client_id` starts with that prefix to share a quota bucket.


Wondering if each of these bullets applies to a specific level shown above. If so, you could use numbers to help readers quickly make the match/connection. I could be all wrong here, but if not, it sure would help me to quickly make the connection between the bullets here and the various levels above.

These sections have been reorganized: https://deploy-preview-1596--redpanda-docs-preview.netlify.app/current/manage/cluster-maintenance/about-throughput-quotas/#quota-precedence-and-tracking

Only kept list item #3 as the others are explained in the table itself

modules/manage/pages/cluster-maintenance/about-throughput-quotas.adoc

modules/manage/pages/cluster-maintenance/manage-throughput.adoc

Feediver1

Left several comments. Please fix all format/tagging errors.

Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com>

kbatuigas added 7 commits March 2, 2026 15:47

Add user quotas and align existing doc with how-to topic template

1a12bf0

Move more content out into new concepts doc

5d261b8

Add rpk cluster config set example for broker limits

024a66e

Minor edit

c0f54ba

Reorganize how-to

d8ef762

Add new conceptual doc about throughput quotas

a59ab7a

Add new doc to nav

6d15ae9

kbatuigas requested a review from a team as a code owner March 3, 2026 03:56

kbatuigas requested a review from pgellert March 3, 2026 18:05

Add user quotas to 26.1 What's New

b3f4f2c

pgellert reviewed Mar 4, 2026

View reviewed changes

kbatuigas and others added 5 commits March 5, 2026 12:34

Apply suggestions from code review

8c41a46

Co-authored-by: Gellért Peresztegi-Nagy <gellert.nagy@redpanda.com>

Apply edits per review

99ef1aa

Update rpk examples

98b835a

Minor style edits

54d4a60

Add glossterms

9c1ed85

kbatuigas requested review from mattschumpert and pgellert March 5, 2026 23:35

kbatuigas commented Mar 5, 2026

View reviewed changes

mattschumpert approved these changes Mar 6, 2026

View reviewed changes

kbatuigas added 3 commits March 6, 2026 16:03

Address comments from SME review

c5d47f9

Minor edit

228e201

Minor edit

4bcbaed

pgellert approved these changes Mar 9, 2026

View reviewed changes